Introduce server sessions #198

tiginamaria · 2025-07-25T17:30:42Z

Introduce a ServerSession to manage multiple connections to the mcp server. Protocall logic of the Server was moved to ServerSession, while MCP resources logic remained in Server

Motivation and Context

Fix the multiple connection issues reported for sse transport
Avoid server duplications during configurations, now every connection creates a session, but the server stays single

How Has This Been Tested?

Added SseIntegrationTest and WebSocketIntegrationTest integration tests to check connection with single and multiple clients

Breaking Changes

This change caused several depreciations:

The Server -> Protocol inheritance (which caused single connection issue) should be removed in future releases, now, all the methods inherited from Protocall marked as Deprecated with a Warning
Websocket ktor server initialization changes in order not to create server instance per connection

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

tiginamaria · 2025-07-25T17:34:26Z

...monMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/WebSocketMcpKtorServerExtensions.kt

+    var session: ServerSession? = null
+    try {
+        session = server.connectSession(transport)
+        awaitCancellation()


Finishes without await in tests, not sure if it's a right approach to fix it, please take a look here! Really need some help here

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt

devcrocod

The PR looks good to me overall!

Please take a look at my comments.
My main concern is about the behavior of the Server
It would also be great to update the existing samples and the README accordingly

api/kotlin-sdk.api

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/KtorServer.kt

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt

Copilot

Pull Request Overview

This PR introduces server sessions to manage multiple connections to MCP servers. The implementation moves protocol logic from the Server class to a new ServerSession class, allowing the server to handle multiple simultaneous connections while maintaining a single server instance.

Introduces ServerSession class for managing individual client connections
Moves protocol-level functionality from Server to ServerSession
Updates WebSocket and SSE transport implementations to support multiple sessions
Adds comprehensive integration tests for both single and multiple connection scenarios

Reviewed Changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
SseIntegrationTest.kt	New integration test verifying SSE transport with single and multiple client connections
WebSocketIntegrationTest.kt	New integration test verifying WebSocket transport with single and multiple client connections
SseTransportTest.kt	Updates to use new `SseTransportManager` instead of direct transport map
WebSocketMcpTransport.kt	Adds debug logging for WebSocket transport operations
Protocol.kt	Refactors logger variable naming for consistency
WebSocketMcpServerTransport.kt	Adds debug logging for session header validation
WebSocketMcpKtorServerExtensions.kt	Major refactor to support session-based architecture with new API and deprecation warnings
ServerSession.kt	New class implementing session-specific protocol handling moved from Server
Server.kt	Refactored to manage multiple sessions while maintaining resource management
SSEServerTransport.kt	Removes unused import
KtorServer.kt	Introduces `SseTransportManager` for better session management
WebSocketMcpKtorClientExtensions.kt	Adds debug logging for client connection process
WebSocketClientTransport.kt	Adds debug logging for session initialization
SSEClientTransport.kt	Adds debug logging for message sending and endpoint connection
Client.kt	Improves error handling during connection initialization
kotlin-sdk.api	Updates API surface to include new classes and deprecation warnings

Comments suppressed due to low confidence (1)

src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/integration/WebSocketIntegrationTest.kt:37

The test method name 'client should be able to connect to websocket server 2' is unclear. The '2' suffix doesn't indicate what distinguishes this test from others. Consider renaming to something more descriptive like 'client establishes websocket connection successfully'.

    fun `client should be able to connect to websocket server 2`() = runTest {

...commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/integration/WebSocketIntegrationTest.kt

src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/integration/SseIntegrationTest.kt

...monMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/WebSocketMcpKtorServerExtensions.kt

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/Client.kt

e5l

Hey @tiginamaria, thank you for the PR. Could you add a sample as a docs page illustrating what the difference will be between kotlin and the original TypeScript API?

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/Client.kt

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerSession.kt

devcrocod

lgtm!

kpavlov

Thank you, @tiginamaria, @devcrocod. Callback chaining implementation is very simple and it can be improved in a separate PR along with the tests.

kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/KtorServer.kt

...commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/integration/WebSocketIntegrationTest.kt

kpavlov · 2025-08-26T10:03:36Z

...commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/integration/WebSocketIntegrationTest.kt

+            withContext(Dispatchers.Default) {
+                withTimeout(1000) {


Can it be replaced with runTest(timeout=5.seconds){ ... }?

Suggested change

withContext(Dispatchers.Default) {

withTimeout(1000) {

Agreed, but why exactly 5 seconds?

...commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/integration/WebSocketIntegrationTest.kt

kpavlov · 2025-08-26T10:13:29Z

...sdk-test/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/client/SseTransportTest.kt

-//                        }
-//
-//                        start()
-//                    }


Is it possible to remove commented code?

kpavlov · 2025-08-26T10:18:55Z

...monMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/WebSocketMcpKtorClientExtensions.kt

@@ -36,6 +39,8 @@ public suspend fun HttpClient.mcpWebSocket(
            version = LIB_VERSION,
        ),
    )
+    logger.debug { "Client started to connect to server" }


nit: should it be trace level? It might be too verbose for debug.

kpavlov · 2025-08-26T10:20:47Z

...ore/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/WebSocketMcpTransport.kt

@@ -53,7 +58,8 @@ public abstract class WebSocketMcpTransport : AbstractTransport() {
            while (true) {
                val message = try {
                    session.incoming.receive()
-                } catch (_: ClosedReceiveChannelException) {
+                } catch (e: ClosedReceiveChannelException) {


e is actually not used. Can be reverted to _

...-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerSession.kt

kpavlov · 2025-08-26T10:38:07Z

...-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerSession.kt

+     * @return The result of the ping request.
+     * @throws IllegalStateException If for some reason the method is not supported or the connection is closed.
+     */
+    public suspend fun ping(): EmptyRequestResult = request<EmptyRequestResult>(PingRequest())


nit: all explicit type arguments can be removed

Suggested change

public suspend fun ping(): EmptyRequestResult = request<EmptyRequestResult>(PingRequest())

public suspend fun ping(): EmptyRequestResult = request<>(PingRequest())

devcrocod · 2025-08-26T11:17:56Z

@tiginamaria
please check tests failed:

io.modelcontextprotocol.kotlin.sdk.integration.SseIntegrationTest.client should be able to connect to sse server[js, node] FAILED
    IllegalStateException at /mnt/agent/work/8d547b974a7be21f/ktor-server/ktor-server-cio/jsAndWasmShared/src/io/ktor/server/cio/internal/CoroutineUtils.jsAndWasmShared.kt:14

io.modelcontextprotocol.kotlin.sdk.integration.SseIntegrationTest.single sse connection[js, node] FAILED
    IllegalStateException at /mnt/agent/work/8d547b974a7be21f/ktor-server/ktor-server-cio/jsAndWasmShared/src/io/ktor/server/cio/internal/CoroutineUtils.jsAndWasmShared.kt:14

io.modelcontextprotocol.kotlin.sdk.integration.SseIntegrationTest.multiple sse connections[js, node] FAILED
    IllegalStateException at /mnt/agent/work/8d547b974a7be21f/ktor-server/ktor-server-cio/jsAndWasmShared/src/io/ktor/server/cio/internal/CoroutineUtils.jsAndWasmShared.kt:14

io.modelcontextprotocol.kotlin.sdk.integration.WebSocketIntegrationTest.client should be able to connect to websocket server 2[js, node] FAILED
    IllegalStateException at /mnt/agent/work/8d547b974a7be21f/ktor-server/ktor-server-cio/jsAndWasmShared/src/io/ktor/server/cio/internal/CoroutineUtils.jsAndWasmShared.kt:14

io.modelcontextprotocol.kotlin.sdk.integration.WebSocketIntegrationTest.single websocket connection[js, node] FAILED
    IllegalStateException at /mnt/agent/work/8d547b974a7be21f/ktor-server/ktor-server-cio/jsAndWasmShared/src/io/ktor/server/cio/internal/CoroutineUtils.jsAndWasmShared.kt:14

io.modelcontextprotocol.kotlin.sdk.integration.WebSocketIntegrationTest.multiple websocket connections[js, node] FAILED
    IllegalStateException at /mnt/agent/work/8d547b974a7be21f/ktor-server/ktor-server-cio/jsAndWasmShared/src/io/ktor/server/cio/internal/CoroutineUtils.jsAndWasmShared.kt:14

runBlocking is not supported for wasm

devcrocod · 2025-08-26T11:52:08Z

I found the problem: these tests use stop for the Ktor server, but it should be stopSuspend

tiginamaria requested a review from devcrocod July 25, 2025 17:31

tiginamaria commented Jul 25, 2025

View reviewed changes

src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt Outdated Show resolved Hide resolved

tiginamaria force-pushed the tigina/server-session branch from f33add5 to 0265956 Compare July 25, 2025 20:48

devcrocod requested changes Jul 27, 2025

View reviewed changes

devcrocod requested review from e5l, sdubov and Copilot July 27, 2025 15:48

Copilot AI reviewed Jul 27, 2025

View reviewed changes

e5l requested changes Jul 28, 2025

View reviewed changes

devcrocod mentioned this pull request Jul 30, 2025

FEAT: Support almost all Tier 1, 2 and 3 Kotlin targets #151

Merged

9 tasks

tiginamaria force-pushed the tigina/server-session branch from 560c13f to f9f1a15 Compare August 4, 2025 15:58

devcrocod mentioned this pull request Aug 7, 2025

Why is Kotlin SDK always left behind? #218

Open

tiginamaria force-pushed the tigina/server-session branch from fcf25b6 to 18a4174 Compare August 20, 2025 09:33

tiginamaria requested review from devcrocod and e5l August 21, 2025 12:22

tiginamaria marked this pull request as ready for review August 25, 2025 14:26

devcrocod approved these changes Aug 25, 2025

View reviewed changes

tiginamaria added 11 commits August 25, 2025 20:27

Introduce server session

e2400cf

Fix websocket ktor server implementation, add test and logs

156a021

Fix imports

aef851d

Change api

a3cce6c

Changes after rebase

e6a012d

Remove Protocol from Server

98d7122

Fix compilation

f37d901

Fix linter, add enums instead of strings in capabilities assertion

a356277

Dump api

a4b3da8

Fix tests

472d368

Fix tests

239fc97

devcrocod force-pushed the tigina/server-session branch from e26cea1 to 239fc97 Compare August 25, 2025 18:27

kpavlov approved these changes Aug 26, 2025

View reviewed changes

	public suspend fun ping(): EmptyRequestResult = request<EmptyRequestResult>(PingRequest())
	public suspend fun ping(): EmptyRequestResult = request<>(PingRequest())

Introduce server sessions #198

Are you sure you want to change the base?

Introduce server sessions #198

Uh oh!

Conversation

tiginamaria commented Jul 25, 2025

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

tiginamaria Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

devcrocod left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

e5l left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

devcrocod left a comment

Choose a reason for hiding this comment

Uh oh!

kpavlov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kpavlov Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

devcrocod Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kpavlov Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

kpavlov Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

kpavlov Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kpavlov Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

devcrocod commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devcrocod commented Aug 26, 2025

Uh oh!

Uh oh!

tiginamaria Jul 25, 2025 •

edited

Loading

devcrocod commented Aug 26, 2025 •

edited

Loading